/*
 * DataSet.java
 *
 * Created on December 10, 2007, 13:06 PM
 */
package org.osdtsystem.dataset;

import java.util.Collection;

/**
 * Interface for a data set. Each data point has
 * a unique integer-valued identifier in the data set, which means that the
 * data set can be viewed as a collection of integers.
 * @author Martin Haulrich and Matthias Buch-Kromann
 */
public interface Dataset extends Collection<Integer> {
    /**
     * The dimensionality of the dataset. Ie, the number of strings associated
     * with each data point.
     * @return the dimensionality of the dataset
     */
    public int dimensionality();


    /**
     * Insert data point in the data set.
     * @param dataPoint the data point
     * @return the identifier for the new data point
     */
    public int append(DataPoint dataPoint);

    /**
     * Remove the data point with the given identifier.
     * @param identifier the identifier for the data point
     */
    public void removeID(int identifier);

    /**
     * The total weight of the data points in the data set. This is the sum
     * of the weights of the data points in the data set.
     * @return the total weight
     */
    public double weight();

    /**
     * The data point corresponding to the identifer.
     * @param identifier the identifier for the data point
     * @return the data point
     */
    public DataPoint dataPoint(int identifier);

    /**
     * Compute the intersection between two data sets.
     * @param otherDataSet the other data set
     * @return the intersection between this data set and the other data sets
     */
    public Dataset intersection(Dataset otherDataSet);

    /**
     * Compute the union between two data sets.
     * @param otherDataSet the other data set
     * @return the union between this data set and the other data sets
     */
    public Dataset union(Dataset otherDataSet);

    /**
     * Compute the difference between two data sets.
     * @param otherDataSet the other data set
     * @return the difference between this data set and the other data sets
     */
    public Dataset difference(Dataset otherDataSet);

    /**
     * The base data set where the data are actually stored.
     * @return the base data set
     */
    public DatasetRaw baseDataSet();

    /**
     * Return an empty dataset.
     * @return the empty data set
     */
    public DatasetRaw emptyDataset();

    /**
     * Trim the data set to its minimal size. This method may be slow.
     * It can be used to reduce the memory footprint of the data set when
     * no more data points will be added to or removed from it.
     */
    public void trimToSize();

    @Override
    public DatasetIterator iterator();
}
